Miles Sound System SDK 7.2a

DDK Function: 503H Install Timbre Set

Discussion

Input:

AX = 503H
BX = Driver number
XMIDI TIMB chunk image copied to DST MIDI_data[] area

Output:

AX = 1: All timbres successfully installed (or already present)
AX = 0: Error (BX = bank/patch specifier for failed operation)

The term "timbre" (pronounced TIM-ber or TAM-ber), as used in all MSS documentation, refers to the set of data which determines all performance characteristics of a musical instrument. The data describing a timbre may occupy as little as 14 bytes for a Yamaha OPL2-type FM voice, or several hundred kilobytes for an ultra-high-quality wavetable instrument definition. Additionally, some synthesizers may require that multiple levels of "patches," "waveforms," "multisamples," "presets," or other constructs be considered as aspects of the timbre definition as it relates to MSS-based MIDI performance.

Under the MSS 2.X standard, the API module allowed extensive application-level control over the management of instrument data. Instrument data for all supported synthesizers, regardless of voice format, was maintained in a GTL file, or Global Timbre Library file. The GTL file concept was ideal for working with highly-programmable synthesizers with relatively small timbre data sizes, such as the OPL2, OPL3, and Roland MT-32 platforms. However, MSS 2.X's technique of allowing the application program to manage timbres directly proved inflexible with the arrival of General MIDI and its accompanying entourage of wavetable synthesizers. Often, instrument definitions for the new synthesizers could no longer be shoehorned into monolithic, easily managed blocks of application memory. Discouraged by a multitude of incompatible, proprietary "standards," third-party tools for the creation and archival of wavetable samples were rare to nonexistent. OEM driver developers were thwarted in their efforts to resolve these issues by MSS 2.X's strict prohibition against DOS or other system calls within drivers.

The GTL standard remains in place under the current MSS, but several fundamental changes have occurred in the area of timbre management. The most important of these changes is that the driver, not the application, is now responsible for accessing GTL files, proprietary instrument library files, or both. Virtually all MSS 2.X applications contained a "timbre request" loop similar to the following:


while ((treq = AIL_timbre_request(driver,sequence)) != 0xffff)
{
   bank = treq / 256; patch = treq % 256;
   data = load_global_timbre(GTL,bank,patch);
   if (timb != NULL)
   {
      AIL_install_timbre(driver,bank,patch,data);
      free(timb);
   }
}

This loop would typically be executed after registering an XMIDI sequence with MSS, and before starting playback. The old AIL_timbre_request function would examine the XMIDI file image to check for timbres used by the sequence which did not correspond to instruments currently present in the timbre cache. If any timbres were "requested" in this manner, the application would open the GTL file and fetch the timbre's data block, supplying it to the driver with a call to AIL_install_timbre. This process would continue until all timbres required to play the XMIDI sequence had been uploaded to the synthesizer or cached in system RAM, depending on the synthesizer platform.

Current MSS drivers which support MSS 2.X-compatible Global Timbre Library files must implement the basic algorithm above in Function 503H (Install Timbre Set). Most OEM-developed drivers, however, will not need to deal with GTL compatibility. Instead, the Function 503H (Install Timbre Set) handlers in these drivers will either return immediately with AX = -1 if the synthesizer does not support uploadable instruments or if the complete instrument set is present in ROM, or, in cases where uploadable instruments are supported and/or required, handle the necessary uploading and memory management tasks in a manner transparent to MSS.

The list of timbres required to play a given XMIDI sequence appears in the sequence's XMIDI file image in the form of an IFF (Interchange File Format) chunk of type TIMB:


[
   TIMB
   U16 # of timbre list entries, 0-16384
   {
      U8 patch number 0-127
      U8 timbre bank 0-127
   }
   ...
]

Prior to calling this function, the entire TIMB chunk is copied to the DST's 512-byte MIDI_data[] array. This is the same area of memory used to communicate with Function 502H (Transmit MIDI Data). TIMB chunks longer than 512 bytes will be split into smaller sub-chunks and passed in subsequent calls to the function. The patch number for each timbre entry corresponds to the normal MIDI Program Change controller value used to associate a patch with a given MIDI channel. Through the addition of the XMIDI Patch Bank Select controller (114) to the MSS MIDI implementations, the basic MIDI Program Change architecture has been extended to accommodate up to 16,384 unique instruments by combining a timbre bank (also called a patch bank) value with each patch number. Patch number/timbre bank pairs are often expressed as two-byte integers or bank/patch specifiers, in which the low byte corresponds to the patch number and the high byte corresponds to its timbre bank.

By default, the timbre bank value for channels which do not use the XMIDI Patch Bank Select controller is 0. Under MSS 2.X, patch bank 0 corresponded to the default MT-32 instrument set, or its emulated equivalent on the Ad Lib and other synthesizers. Under the current MSS, however, patch bank 0 now corresponds to the General MIDI patch set. Other bank numbers, chosen by the composer, must be used for custom instruments or MT-32 emulation. This change has been made in response to the overwhelming success of General MIDI in the interactive music field, and the accompanying decline in importance of the older MT-32 MIDI standard among MSS users.

This function may safely perform DOS or other system-level accesses where necessary. It will never be called from an unprotected asynchronous interrupt handler, or under conditions which preclude the availability of DOS and BIOS services.

Group: DOS XMIDI Sound Driver Interface
Related Functions: AIL_install_timbre